home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3s / wcstring.z / wcstring
Encoding:
Text File  |  2001-04-17  |  23.7 KB  |  188 lines
  1.  
  2.  
  3.  
  4. wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))                                                      wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _wwww_cccc_ssss_tttt_rrrr_iiii_nnnn_gggg_:::: _wwww_cccc_ssss_cccc_aaaa_tttt_,,,, _wwww_ssss_cccc_aaaa_tttt_,,,, _wwww_cccc_ssss_nnnn_cccc_aaaa_tttt_,,,, _wwww_ssss_nnnn_cccc_aaaa_tttt_,,,, _wwww_cccc_ssss_cccc_mmmm_pppp_,,,, _wwww_ssss_cccc_mmmm_pppp_,,,, _wwww_cccc_ssss_nnnn_cccc_mmmm_pppp_,,,, _wwww_ssss_nnnn_cccc_mmmm_pppp_,,,,
  10.      _wwww_cccc_ssss_cccc_oooo_llll_llll_,,,, _wwww_cccc_ssss_cccc_pppp_yyyy_,,,, _wwww_ssss_cccc_pppp_yyyy_,,,, _wwww_cccc_ssss_nnnn_cccc_pppp_yyyy_,,,, _wwww_ssss_nnnn_cccc_pppp_yyyy_,,,, _wwww_cccc_ssss_llll_eeee_nnnn_,,,, _wwww_ssss_llll_eeee_nnnn_,,,, _wwww_cccc_ssss_cccc_hhhh_rrrr_,,,, _wwww_ssss_cccc_hhhh_rrrr_,,,,
  11.      _wwww_cccc_ssss_rrrr_cccc_hhhh_rrrr_,,,, _wwww_ssss_rrrr_cccc_hhhh_rrrr_,,,, _wwww_cccc_ssss_pppp_bbbb_rrrr_kkkk_,,,, _wwww_ssss_pppp_bbbb_rrrr_kkkk_,,,, _wwww_cccc_ssss_ssss_pppp_nnnn_,,,, _wwww_ssss_ssss_pppp_nnnn_,,,, _wwww_ssss_cccc_ssss_pppp_nnnn_,,,, _wwww_cccc_ssss_tttt_oooo_kkkk_,,,, _wwww_ssss_tttt_oooo_ssss_tttt_rrrr_,,,,
  12.      _wwww_cccc_ssss_wwww_cccc_ssss_,,,, _wwww_cccc_ssss_wwww_iiii_dddd_tttt_hhhh_,,,, _wwww_cccc_wwww_iiii_dddd_tttt_hhhh  -  _wwww_cccc_hhhh_aaaa_rrrr______tttt string operations and type
  13.      transformation
  14.  
  15. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  16.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_wwww_cccc_hhhh_aaaa_rrrr_...._hhhh_>>>>
  17.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_cccc_aaaa_tttt_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  18.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_cccc_aaaa_tttt_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  19.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_nnnn_cccc_aaaa_tttt_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _ssss_iiii_zzzz_eeee______tttt _n_))))_;;;;
  20.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_nnnn_cccc_aaaa_tttt_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _iiii_nnnn_tttt _n_))))_;;;;
  21.      _iiii_nnnn_tttt _wwww_cccc_ssss_cccc_mmmm_pppp_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  22.      _iiii_nnnn_tttt _wwww_ssss_cccc_mmmm_pppp_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  23.      _iiii_nnnn_tttt _wwww_cccc_ssss_nnnn_cccc_mmmm_pppp_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _ssss_iiii_zzzz_eeee______tttt _n_))))_;;;;
  24.      _iiii_nnnn_tttt _wwww_ssss_nnnn_cccc_mmmm_pppp_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _iiii_nnnn_tttt _n_))))_;;;;
  25.      _iiii_nnnn_tttt _wwww_cccc_ssss_cccc_oooo_llll_llll_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  26.  
  27.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_cccc_pppp_yyyy_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  28.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_cccc_pppp_yyyy_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  29.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_nnnn_cccc_pppp_yyyy_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _ssss_iiii_zzzz_eeee______tttt _n_))))_;;;;
  30.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_nnnn_cccc_pppp_yyyy_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_,,,, _iiii_nnnn_tttt _n_))))_;;;;
  31.      _ssss_iiii_zzzz_eeee______tttt _wwww_cccc_ssss_llll_eeee_nnnn_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_))))_;;;;
  32.      _iiii_nnnn_tttt _wwww_ssss_llll_eeee_nnnn_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_))))_;;;;
  33.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_cccc_hhhh_rrrr_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _c_))))_;;;;
  34.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_cccc_hhhh_rrrr_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_,,,, _iiii_nnnn_tttt _c_))))_;;;;
  35.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_rrrr_cccc_hhhh_rrrr_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_,,,, _iiii_nnnn_tttt _c_))))_;;;;
  36.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_rrrr_cccc_hhhh_rrrr_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_,,,, _iiii_nnnn_tttt _c_))))_;;;;
  37.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_pppp_bbbb_rrrr_kkkk_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  38.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_ssss_pppp_bbbb_rrrr_kkkk_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  39.      _iiii_nnnn_tttt _wwww_cccc_ssss_ssss_pppp_nnnn_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  40.      _iiii_nnnn_tttt _wwww_ssss_ssss_pppp_nnnn_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  41.      _iiii_nnnn_tttt _wwww_ssss_cccc_ssss_pppp_nnnn_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  42.  
  43.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_tttt_oooo_kkkk_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  44.  
  45.      _cccc_hhhh_aaaa_rrrr _****_wwww_ssss_tttt_oooo_ssss_tttt_rrrr_((((_cccc_hhhh_aaaa_rrrr _****_s_1_,,,, _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  46.  
  47.      _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_wwww_cccc_ssss_wwww_cccc_ssss_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_1_,,,, _cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_2_))))_;;;;
  48.  
  49.      _iiii_nnnn_tttt _wwww_cccc_ssss_wwww_iiii_dddd_tttt_hhhh_((((_cccc_oooo_nnnn_ssss_tttt _wwww_cccc_hhhh_aaaa_rrrr______tttt _****_s_,,,, _ssss_iiii_zzzz_eeee______tttt _n_))))_;;;;
  50.  
  51.  
  52.                                                                         PPPPaaaaggggeeee 1111
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59. wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))                                                      wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))
  60.  
  61.  
  62.  
  63.      _iiii_nnnn_tttt _wwww_cccc_wwww_iiii_dddd_tttt_hhhh_((((_wwww_cccc_hhhh_aaaa_rrrr______tttt _w_c_))))_;;;;
  64.  
  65. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN ((((IIIInnnntttteeeerrrrnnnnaaaattttiiiioooonnnnaaaallll FFFFuuuunnnnccccttttiiiioooonnnnssss))))
  66.      The arguments _s_1, _s_2, and _s point to _wwww_cccc_hhhh_aaaa_rrrr______tttt strings (that is, arrays of
  67.      _wwww_cccc_hhhh_aaaa_rrrr______tttt characters terminated by a _wwww_cccc_hhhh_aaaa_rrrr______tttt null character).  The
  68.      functions _wwww_cccc_ssss_cccc_aaaa_tttt, _wwww_ssss_cccc_aaaa_tttt, _wwww_cccc_ssss_nnnn_cccc_aaaa_tttt, _wwww_ssss_nnnn_cccc_aaaa_tttt, _wwww_cccc_ssss_cccc_pppp_yyyy, _wwww_ssss_cccc_pppp_yyyy, _wwww_cccc_ssss_nnnn_cccc_pppp_yyyy and
  69.      _wwww_ssss_nnnn_cccc_pppp_yyyy all modify _s_1.  These functions do not check for an overflow
  70.      condition of the array pointed to by _s_1.
  71.  
  72.      _wwww_cccc_ssss_cccc_aaaa_tttt and _wwww_ssss_cccc_aaaa_tttt append a copy of the _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2 to the end of the
  73.      _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_1.  _wwww_cccc_ssss_nnnn_cccc_aaaa_tttt and _wwww_ssss_nnnn_cccc_aaaa_tttt append at most _n _wwww_cccc_hhhh_aaaa_rrrr______tttt
  74.      characters.  Each function returns _s_1.
  75.  
  76.      _wwww_cccc_ssss_cccc_mmmm_pppp and _wwww_ssss_cccc_mmmm_pppp compare its arguments and returns an integer less than,
  77.      equal to, or greater than _0000, depending on whether _s_1 is less than, equal
  78.      to, or greater than _s_2.  _wwww_cccc_ssss_nnnn_cccc_mmmm_pppp and _wwww_ssss_nnnn_cccc_mmmm_pppp make the same comparison but
  79.      look at most at _n _wwww_cccc_hhhh_aaaa_rrrr______tttt characters.
  80.  
  81.      _wwww_cccc_ssss_cccc_pppp_yyyy and _wwww_ssss_cccc_pppp_yyyy copy _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2 to _s_1, stopping after the _wwww_cccc_hhhh_aaaa_rrrr______tttt
  82.      null character has been copied.  _wwww_cccc_ssss_nnnn_cccc_pppp_yyyy and _wwww_ssss_nnnn_cccc_pppp_yyyy copy exactly _n
  83.      _wwww_cccc_hhhh_aaaa_rrrr______tttt characters, truncating _s_2 or adding _wwww_cccc_hhhh_aaaa_rrrr______tttt null characters to
  84.      _s_1, if necessary.  The result will not be _wwww_cccc_hhhh_aaaa_rrrr______tttt null-terminated if the
  85.      length of _s_2 is _n or more.  Each function returns _s_1.
  86.  
  87.      _wwww_cccc_ssss_llll_eeee_nnnn and _wwww_ssss_llll_eeee_nnnn return the number of _wwww_cccc_hhhh_aaaa_rrrr______tttt characters in _s, not
  88.      including the terminating _wwww_cccc_hhhh_aaaa_rrrr______tttt null character.
  89.  
  90.      _wwww_cccc_ssss_cccc_hhhh_rrrr, _wwww_ssss_cccc_hhhh_rrrr, _wwww_cccc_ssss_rrrr_cccc_hhhh_rrrr and _wwww_ssss_rrrr_cccc_hhhh_rrrr return a pointer to the first and last
  91.      occurrence, respectively, of _wwww_cccc_hhhh_aaaa_rrrr______tttt character _c in _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s, or
  92.      a null pointer, if _c does not occur in the string.  The _wwww_cccc_hhhh_aaaa_rrrr______tttt null
  93.      character terminating a string is considered to be part of the string.
  94.  
  95.      _wwww_cccc_ssss_pppp_bbbb_rrrr_kkkk and _wwww_ssss_pppp_bbbb_rrrr_kkkk return a pointer to the first occurrence in _wwww_cccc_hhhh_aaaa_rrrr______tttt
  96.      string _s_1 of any _wwww_cccc_hhhh_aaaa_rrrr______tttt character from _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2, or a null
  97.      pointer if there is no _wwww_cccc_hhhh_aaaa_rrrr______tttt character from _s_2 in _s_1.
  98.  
  99.      _wwww_cccc_ssss_ssss_pppp_nnnn and _wwww_ssss_ssss_pppp_nnnn return the length of the initial segment of _wwww_cccc_hhhh_aaaa_rrrr______tttt
  100.      string _s_1, which consists entirely of _wwww_cccc_hhhh_aaaa_rrrr______tttt characters from _wwww_cccc_hhhh_aaaa_rrrr______tttt
  101.      string _s_2.  _wwww_ssss_cccc_ssss_pppp_nnnn returns the length of the initial segment of _wwww_cccc_hhhh_aaaa_rrrr______tttt
  102.      string _s_1, which does not consist entirely of _wwww_cccc_hhhh_aaaa_rrrr______tttt characters from
  103.      _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2.
  104.  
  105.      _wwww_cccc_ssss_tttt_oooo_kkkk treats the _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_1 as a sequence of zero or more text
  106.      tokens, separated by spans of one or more _wwww_cccc_hhhh_aaaa_rrrr______tttt characters from the
  107.      separator _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2.  The first call (with the pointer _s_1
  108.      specified) returns a pointer to the first _wwww_cccc_hhhh_aaaa_rrrr______tttt character of the first
  109.      token, and writes a _wwww_cccc_hhhh_aaaa_rrrr______tttt null character into _s_1 immediately following
  110.      the returned token.  The function keeps track of its position in the
  111.      _wwww_cccc_hhhh_aaaa_rrrr______tttt string between separate calls, so that subsequent calls (which
  112.      must be made with the first argument a null pointer) will progress
  113.      through the _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_1 immediately following that token.
  114.      Similarly, subsequent calls will progress through the _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_1
  115.  
  116.  
  117.  
  118.                                                                         PPPPaaaaggggeeee 2222
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125. wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))                                                      wwwwccccssssttttrrrriiiinnnngggg((((3333SSSS))))
  126.  
  127.  
  128.  
  129.      until no tokens remain.  The _wwww_cccc_hhhh_aaaa_rrrr______tttt separator string _s_2 may be different
  130.      from call to call.  A null pointer is returned when no token remains in
  131.      _s_1.
  132.  
  133.      _wwww_ssss_tttt_oooo_ssss_tttt_rrrr transforms _wwww_cccc_hhhh_aaaa_rrrr______tttt characters in _wwww_cccc_hhhh_aaaa_rrrr______tttt string _s_2 into EUC, and
  134.      transfers them to character string _s_1, stopping after the _wwww_cccc_hhhh_aaaa_rrrr______tttt null
  135.      character has been processed.
  136.  
  137.      _wwww_cccc_ssss_cccc_oooo_llll_llll compares the wide character string pointed to by _s_1 to the wide
  138.      character string pointed to by _s_2, both interpreted as appropriate to the
  139.      LC_COLLATE category of the current locale.  Upon successful completion,
  140.      _wwww_cccc_ssss_cccc_oooo_llll_llll returns an integer greater than, equal to or less than zero,
  141.      according to whether the wide character string pointed to by _s_1 is
  142.      greater than, equal to or less than the wide character string pointed to
  143.      by _s_2, when both are interpreted as appropriate to the current locale.
  144.      On error, _wwww_cccc_ssss_cccc_oooo_llll_llll may set _e_r_r_n_o, but no return value is reserved to
  145.      indicate an error.  If _e_r_r_n_o is set to EINVAL, then the _s_1 or _s_2
  146.      arguments contain wide character codes outside the domain of the
  147.      collating sequence.
  148.  
  149.      _wwww_cccc_ssss_wwww_cccc_ssss locates the first occurrence in the wide character string pointed
  150.      to by _s_1 of the sequence of wide-character codes (excluding the
  151.      terminating null wide-character code) in the wide character string
  152.      pointed to by _s_2.  Upon successful completion, _wwww_cccc_ssss_wwww_cccc_ssss returns a pointer
  153.      to the located wide character string or a null pointer if the wide
  154.      character string is not found.  If _s_2 points to a wide character string
  155.      with zero length, the function returns _s_1.
  156.  
  157.      _wwww_cccc_ssss_wwww_iiii_dddd_tttt_hhhh determines the number of column positions required for _n wide-
  158.      character codes (or fewer than _n wide-character codes if a null wide-
  159.      character code is encountered before _n wide-character codes are
  160.      exhausted) in the string pointed to by _s.  _wwww_cccc_ssss_wwww_iiii_dddd_tttt_hhhh either returns _0 (if
  161.      _s points to a null wide-character code), or returns the number of column
  162.      positions to be occupied by the wide character string pointed to by _s, or
  163.      returns -_1 (if any of the first _n wide-character codes in the wide
  164.      character string pointed to by _s is not a printing wide-character code).
  165.  
  166.      _wwww_cccc_wwww_iiii_dddd_tttt_hhhh determines the number of column positions required for the wide
  167.      character _w_c.  The value of _w_c must be a character representable as a
  168.      _wwww_cccc_hhhh_aaaa_rrrr______tttt, and must be a wide-character code corresponding to a valid
  169.      character in the current locale.  _wwww_cccc_wwww_iiii_dddd_tttt_hhhh either returns _0 (if _w_c is a
  170.      null wide-character code), or returns the number of column positions to
  171.      be occupied by the wide-character code _w_c, or returns -_1 (if _w_c does not
  172.      correspond to a prinable wide-character code).
  173.  
  174. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  175.      _mmmm_aaaa_llll_llll_oooo_cccc(3C), _wwww_iiii_dddd_eeee_cccc(3S), _mmmm_aaaa_llll_llll_oooo_cccc(3X).
  176.  
  177. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  178.      On success, _wwww_ssss_tttt_oooo_ssss_tttt_rrrr returns _s_1.  If an illegal byte sequence is detected,
  179.      a null pointer is returned and _eeee_rrrr_rrrr_nnnn_oooo is set to _EEEE_IIII_LLLL_SSSS_EEEE_QQQQ.
  180.  
  181.  
  182.  
  183.  
  184.                                                                         PPPPaaaaggggeeee 3333
  185.  
  186.  
  187.  
  188.